Option Explicit

'################################################################
' Property
'################################################################
' 获取当前 DataFrame 中的数据数量
Public Property Get Size() As Long
End Property

' 获取列数
Public Property Get ColumnCount() As Integer
End Property

' 获取所有列名
Public Property Get ColumnNames() As Collection
End Property

' 获取当前 DataFrame 的 Id
Public Property Get ID() As String
End Property

' 设置当前 DataFrame 的 Id
Public Property Let ID(ByRef val As String)
End Property

'################################################################
' Function
'################################################################
'--------------------------------------------------
' 行操作
'--------------------------------------------------
' 添加指定数量的空行
' @param count 需要添加的行数，默认为 1 行
Public Sub appendEmptyRow(Optional count As Long = 1)
End Sub

' 新增一行，并拷贝指定行的数据到这个新行
' @param index 需要拷贝的数据行的索引
' @optional-param needDescriptor 如果数据存在描述符，是否需要拷贝，默认=False
Public Sub copyAndAppendRow(ByRef index As Long, Optional ByRef needDescriptor As Boolean=False)
End Sub

' 直接添加一行数据
' 如果参数数量为 0，则不会执行添加的操作
' 如果参数数量比列的数量少，则剩余的列设置为 Empty
' 如果参数数量比列的数量多，则多余的参数会被忽略
'
' @param colDatas 这一行的每一列的数据
Public Sub appendRowByColDatas(ParamArray colDatas() As Variant)
End Sub

' 直接添加一行数据
' 如果参数数量为 0，则不会执行添加的操作
' 如果参数数量比列的数量少，则剩余的列设置为 Empty
' 如果参数数量比列的数量多，则多余的参数会被忽略
'
' @param colDatas 这一行的每一列的数据
Public Sub appendRowByColDataArray(ByRef colDatas As Variant)
End Sub

' 删除指定索引的行
' 只删除当前对象内的数据
'
' @param index 需要删除的列的索引
'                 如果超出了索引范围，将会抛出异常
Public Sub delRow(ParamArray indexes() As Variant)
End Sub

' 删除指定索引的行 (使用数组)
' 只删除当前对象内的数据
'
' @param index 需要删除的列的索引
'                 如果超出了索引范围，将会抛出异常
Public Sub delRowByIndexArray(ByRef indexes As Variant)
End Sub

' 删除指定索引的行
' 如果当前是引用对象，也会直接删除原始对象中的数据
'
' @param index 需要删除的列的索引
'                 如果超出了索引范围，将会抛出异常
Public Sub deepDelRow(ParamArray indexes() As Variant)
End Sub

' 删除指定索引的行 (使用数组)
' 如果当前是引用对象，也会直接删除原始对象中的数据
'
' @param index 需要删除的列的索引
'                 如果超出了索引范围，将会抛出异常
Public Sub deepDelRowByIndexArray(ByRef indexes As Variant)
End Sub

'--------------------------------------------------
' 列操作
'--------------------------------------------------
' 检查是否存在指定的列
'
' @param cIndex 列的索引或列名
'               如果 index 不是数字(索引) 或 字符串(列名)，则抛出异常
Public Function hasColumn(ByRef index As Variant) As Boolean
End Sub

' 检查是否存在指定的列
' 如果当前是引用对象，也会向下搜索每一层引用对象中的列
'
' @param cIndex 列的索引或列名
'               如果 index 不是数字(索引) 或 字符串(列名)，则抛出异常
Public Function deepHasColumn(ByRef index As Variant) As Boolean
End Sub

' 将列索引转换成列名
'
' @param cIndex 列的索引
'               如果超出了索引范围，将会抛出异常
Public Function colIndexToName(ByRef cIndex As Integer) As String
End Function

' 将列名转换成列索引
'
' @param cName 列名
'              如果列名不存在，将会抛出异常
Public Function colNameToIndex(ByRef cName As String) As Integer
End Function

' 获取列对象
'
' @param index 列的索引（可以使用列索引，也可以使用列名）
'              如果超出了索引范围，将会抛出异常
'              如果列名不存在，将会抛出异常
Public Function getCol(ByRef index As Variant) As IDFSeries
End Function

' 删除指定索引的列
' 只删除当前对象内的数据
'
' @param index 需要删除的列的索引（可以使用列索引，也可以使用列名）
'                 如果超出了索引范围，将会抛出异常
'                 如果列名不存在，将会抛出异常
Public Sub delCol(ParamArray indexes() As Variant)
End Sub

' 删除指定索引的列 (使用数组)
' 只删除当前对象内的数据
'
' @param index 需要删除的列的索引（可以使用列索引，也可以使用列名）
'                 如果超出了索引范围，将会抛出异常
'                 如果列名不存在，将会抛出异常
Public Sub delColByIndexArray(ByRef indexes As Variant)
End Sub

' 删除指定索引的列
' 如果当前是引用对象，也会直接删除原始对象中的数据
'
' @param index 需要删除的列的索引（可以使用列索引，也可以使用列名）
'                 如果超出了索引范围，将会抛出异常
'                 如果列名不存在，将会抛出异常
Public Sub deepDelCol(ParamArray indexes() As Variant)
End Sub

' 删除指定索引的列 (使用数组)
' 如果当前是引用对象，也会直接删除原始对象中的数据
'
' @param index 需要删除的列的索引（可以使用列索引，也可以使用列名）
'                 如果超出了索引范围，将会抛出异常
'                 如果列名不存在，将会抛出异常
Public Sub deepDelColByIndexArray(ByRef indexes As Variant)
End Sub

' 向所有列的末尾添加一个新的列
' 如果 colName 在 DataFrame 中已经存在，则抛出异常
' 如果当前是一个切片引用，并且在底层被引用的某个 DataFrame 中已经存在了同名的列，则抛出异常
'
' @param colName 新列的列名
' @param dType 列的类型

Public Sub addCol(ByRef colName As String, Optional ByRef dType As DF_DataType)
End Sub

'--------------------------------------------------
' 描述符操作
'--------------------------------------------------

' 获取指定行的描述器
' 如果不存在，则返回 Nothing
'
' @param index 行索引
' @optional-param needCreate 如果描述信息对象不存在是否需要进行创建。默认值=False
' @return IDFDescriptor 数据描述器
Public Function getRowDescriptor(ByRef index As Long, Optional ByRef needCreate As Boolean = False) As IDFDescriptor
End Function

' 获取指定行列确定的槽位的描述器
' 如果不存在，则返回 Nothing
'
' @param rindex 行索引
' @param cindex 列索引（可以使用列索引，也可以使用列名）
' @optional-param needCreate 如果描述信息对象不存在是否需要进行创建。默认值=False
' @return IDFDescriptor 数据描述器
Public Function getDataDescriptor(ByRef rindex As Long, ByRef cindex As Variant, Optional ByRef needCreate As Boolean = False) As IDFDescriptor
End Function

'--------------------------------------------------
' 数据操作
'--------------------------------------------------
' 读数据
' 使用列索引定位
'
' @param rIndex 行索引
' @param cIndex 列索引
Public Function getDataByColIndex(ByRef rIndex As Long, ByRef cIndex As Integer) As Variant
End Function

' 读数据
' 使用列索引定位
'
' @param rIndex 行索引
' @param cName 列名
Public Function getDataByColName(ByRef rIndex As Long, ByRef cName As String) As Variant
End Function

' 写数据
' 使用列索引定位
'
' @param rIndex 行索引
' @param cIndex 列索引
Public Sub setDataByColIndex(ByRef rIndex As Long, ByRef cIndex As Integer, ByRef val As Variant)
End Sub

' 写数据
' 使用列索引定位
'
' @param rIndex 行索引
' @param cName 列名
Public Sub setDataByColName(ByRef rIndex As Long, ByRef cName As String, ByRef val As Variant)
End Sub

'--------------------------------------------------
' 检索操作
'--------------------------------------------------
' 创建一个过滤器，以辅助完成检索操作
Public Function filter() As DFFilter
End Function

'--------------------------------------------------
' 切片操作
'--------------------------------------------------
' 切片
' 同时切行 + 列
' 如:
'     df.slice(1,3,1, 2,4,2)
'     df.slice(1,3,1, [1,2,3,4])
'     df.slice(1,3,1, ["a","b","c","d"])
'     df.slice([1,2,3,4], ["a","b","c","d"])
'     df.slice([1,2,3,4], 1,3,1)
'
' @optional-param rowStart 行起始位置
' @optional-param rowStop  行终止位置(最终不会包含 stop 的索引)
' @optional-param rowStep  行起始位置
' @optional-param colStart 列起始位置
' @optional-param colStop 列终止位置(最终不会包含 stop 的索引)
' @optional-param colStep 列起始位置
' @optional-param rowIndexes 行索引数组
'                            如果使用了 rowIndexes, 将会忽略 rowStart + rowStop + rowStep 这三个参数
' @optional-param colIndexes 列索引数组（可以使用数值索引，也可以使用列名字符串）
'                            如果使用了 rowIndexes, 将会忽略 colStart + colStop + colStep 这三个参数
'                            如果使用了列名，但是列名不存在，将会抛出异常
Public Function slice( _
    Optional ByRef rowStart As Variant, _
    Optional ByRef rowStop As Variant, _
    Optional ByRef rowStep As Variant=1, _
    Optional ByRef colStart As Variant, _
    Optional ByRef colStop As Variant, _
    Optional ByRef colStep As Variant=1, _
    Optional ByRef rowIndexes As Variant, _
    Optional ByRef colIndexes As Variant _
) As IDataFrame

End Function

'--------------------------------------------------
' 输出操作
'--------------------------------------------------
' 将 DataFrame 中的内容输出到控制台
' 按行输出，每个列之间以【,】分割
' Empty 将会以字符串 "@@EMPTY@@" 的形式输出
'
' @optional-param needColName 是否需要输出所有列名。默认=True
Public Sub printToConsole(Optional ByRef needColName As Boolean = True)
End Sub

' 将 DataFrame 中的内容输出到指定 sheet 中
' 为了保证输出和现实结果相同，所有单元格将会被设置成字符串，并且所有数据将会被转换成字符串后写出
' 为了加速，默认所有的组件将以列为单位写出数据
'
' @param sh 需要写入数据的 sheet 对象
' @optional-param sheetWriteRowNo 数据写入 sheet 对象时的起始行号.
'                                 默认 = 1
'                                 可用类型，Integer 或者 Long
'
'                                 如果行号小于 0，将会自动使用 1
'                                 如果行号大于最大值 1048576, 将会自动使用 1
'                                 从指定的 sheet 行号开始，最多从 DataFrame 中读取并输出 (1048576 - 行号（如果不输出列名，则 + 1）) 行，多余的行将被省略
'
' @optional-param sheetWriteColNo 数据写入 sheet 对象时的起始列号、或者列名.
'                                 默认 = 1
'                                 如果是列号，请使用 Integer 或者 Long
'                                 如果是列名，请使用字符串
'
'                                 如果列号小于 0，将会自动使用 1
'                                 如果列号大于最大值 16384, 将会自动使用 1
'                                 从指定的 sheet 列号开始，最多从 DataFrame 中读取并输出 (16384 - 行号 + 1) 列，多余的列将被省略
' @optional-param needColName 是否需要在第一行输出所有列名。默认=True
' @optional-param dfRowStart 输出的起始行(包括这一行，从 0 开始)
'                          只支持 0、正数，如果输入了一个负数，则自动使用 0
'                          如果 dfRowStart > dfRowEnd，则不输出任何数据
' @optional-param dfRowEnd 输出的结束行(包括这一行，从 0 开始)
'                          只支持 0、正数，如果输入了一个负数，则自动使用最大行索引
' @optional-param rowDescriptorHandler 行描述器的处理方法名
'                                      应该提供一个形如以下形式的 Module 级别方法，来处理每个行描述器
'                                       Sub rowDescriptorMethod(ByRef ctx As DFSheetWriterContext, ByRef descriptor As IDFDescriptor)
'                                           参数 ctx 表示当前正在使用的上下文对象
'                                           参数 descriptor 存在 Nothing 的情况，需要在方法内手动处理
' @optional-param dataDescriptorHandler 每个数据槽位的描述器的处理方法名
'                                      应该提供一个形如以下形式的 Module 级别方法，来处理每个数据槽位的描述器
'                                       Sub rowDescriptorMethod(ByRef ctx As DFSheetWriterContext, ByRef descriptor As IDFDescriptor)
'                                           参数 ctx 表示当前正在使用的上下文对象
'                                           参数 descriptor 存在 Nothing 的情况，需要在方法内手动处理
' @optional-param colFormatMap 各列的 Format 字符串集合
'                              Map<ColIndex/"ColName", "Format String">
'                              如果没有设置当前参数，所有数据将会直接输出
Public Sub printToWorksheet(ByRef sh As Worksheet, _
    Optional ByRef sheetWriteRowNo As Variant = -1, _
    Optional ByRef sheetWriteColNo As Variant = -1, _
    Optional ByRef needColName As Boolean = True, _
    Optional ByRef dfRowStart As Long = -1, _
    Optional ByRef dfRowEnd As Long = -1, _
    Optional ByRef rowDescriptorHandler As String = "", _
    Optional ByRef dataDescriptorHandler As String = "", _
    Optional ByRef colFormatMap As Object _
    )
End Sub

